package PagedFile;

import java.io.IOException;
import java.nio.channels.FileChannel;

/*
 * HOW TO USE PF_Manager
 * PF_Manager is a manager for paged file management.
 * There should be only one PF_Manager in the one db system.
 * Once the upper layer wants to write a record to a file, it should do as follows:
 * 1. Create the file if it never is established, or open it else.
 * 2. The PF_Manager will return a PF_FileHandle for later use.
 * 3. By the PF_FileHandle, one can allocate, or dispose, or get, or unpin data by page.
 * 4. The PF_FileHandle will return a Buffer if one asks for allocating or getting a page.
 * 5. Buffer is managed by the BF_Manager. One can manipulate data in the buffer.
 *    Detailed use of Buffer see Buffer.
 */
public interface PF_Manager_Interface {
	
	/*
	 * This method creates a paged file called fileName.
	 * The file should not already exist.
	 */
	public PF_FileHandle CreateFile(String filename) throws IOException;
	
	/*
	 * This method destroys the paged file whose name is fileName. The file should exist.
	 */
	public void DestroyFile(String filename);
	
	/*
	 * This method opens the paged file whose name is fileName.
	 * The file must already exist and it must have been created using the CreateFile method.
	 * If the method is successful, the fileHandle object is returned.
	 * It is not an error to open the same file more than once if desired,
	 * using a different fileHandle object each time.
	 * Each call to the OpenFile method creates a new "instance" of the open file.
	 */
	public PF_FileHandle OpenFile(String filename) throws IOException;
	
	/*
	 * This method closes the open file instance referred to by fileHandle.
	 * The file must have been opened using the OpenFile method.
	 * All of the file's pages are flushed from the buffer pool when the file is closed.
	 * It is an error to attempt to close a file when any of its pages are still pinned in the buffer pool.
	 */
	public void CloseFile(PF_FileHandle fileHandle);
	
	/*
	 * This method allocates a "scratch" memory page(block) in the buffer pool,
	 * and sets buffer to point to it.
	 * The scratch page is automatically pinned in the buffer pool.
	 * It is often called by PF_FileHandle.AllocatePage()
	 */
	public Buffer AllocateBlock(Block blk, FileChannel fc);
	
	/*
	 * This method disposes of the scratch page in the buffer pool pointed to by buffer,
	 * which must have been allocated previously by PF_Manager::AllocateBlock.
	 * Similar to pinning and unpinning,
	 * one must call PF_Manager::DisposeBlock for each buffer block
	 * obtained by calling PF_Manager::AllocateBlock;
	 * otherwise one will lose pages in the buffer pool permanently.
	 */
	public void DisposeBlock(Buffer buf);
	
}
